package edu.chl.grupp11.aegas.utils;

/**
 * Created by: Pelle Evensen email: pelle@evensen.org
 * 
 * Interface to address the shortcoming of
 * <code>@link java.util.Observable java.util.Observable</code> which is a
 * class, not an interface.
 * 
 * @param <S>
 *            Type of the Observable class.
 * @param <M>
 *            Type of the message sent on updates.
 */

public interface Observable<S, M> {
	/**
	 * Adds an observer to the set of observers for this object, provided that
	 * it is not the same as some observer already in the set.
	 * 
	 * The order in which notifications will be delivered to multiple observers
	 * is not specified.
	 * 
	 * @param l
	 *            The observer to add.
	 * @return <code>true</code> - iff the observer was not already registered;
	 *         false otherwise.
	 */
	public boolean addObserver(Observer<S, M> l);

	/**
	 * Deletes an observer from the set of observers of this object.
	 * 
	 * Passing null to this method will have no effect.
	 * 
	 * @param l
	 *            observer to delete.
	 * @return <code>true</code> if the observer was in the set of registered
	 *         observers; <code>false</code> otherwise.
	 */
	public boolean deleteObserver(Observer<S, M> l);

	/**
	 * Delete all observers.
	 */
	public void deleteObservers();

	/**
	 * Tests if this object has changed.
	 * 
	 * Returns: true if and only if the setChanged method has been called more
	 * recently than the clearChanged method on this object; false otherwise.
	 * 
	 * 
	 * @return <code>true</code> iff the a change has happened since the last
	 *         call to {@link #notifyObservers(Object)}; <code>false</code>
	 *         otherwise.
	 */
	public boolean hasChanged();

	/**
	 * If this object has changed, as indicated by the
	 * <code>{@link #hasChanged()}</code> method, then notify all of its
	 * observers.
	 * 
	 * Directly after this method has completed, <code>hasChanged()</code>
	 * should return <code>false</code>.
	 * 
	 * Each observer has its update method called with two arguments: the
	 * observable object and an object carrying extra information on the state
	 * change.
	 * 
	 * @param o
	 *            extra state information from the observable.
	 * 
	 * @see #hasChanged() hasChanged()
	 * @see Observer#update(Observable, Object)
	 */
	public void notifyObservers(M o);
}
